RCD-CUI Development Context

Guidelines for AI assistants working on this repository.

Project Overview

RCD-CUI is an Ansible framework for NIST 800-171 CUI compliance in research computing environments. It targets RHEL 9/Rocky Linux 9 systems with FreeIPA, Slurm, and HPC infrastructure.

Technology Stack

• Ansible 2.15+: Roles, playbooks, execution environments
• Python 3.9+: Filter plugins, reporting scripts, Pydantic validation
• Jinja2: Templates for documentation and configuration
• Container Runtime: Podman (preferred) or Docker for execution environments

Project Structure

roles/           # Ansible roles (35+) organized by NIST control family
playbooks/       # Site playbooks, assessment, onboarding/offboarding
inventory/       # Hosts and group_vars by security zone
docs/            # Data models and generated documentation
scripts/         # Python tooling (doc generation, validation)
templates/       # Jinja2 templates for documentation
tests/           # Pytest and Molecule tests
specs/           # Feature specifications (historical)

Role Naming Convention

Roles follow the pattern {family}_{function}: - ac_* - Access Control - au_* - Audit and Accountability - cm_* - Configuration Management - ia_* - Identification and Authentication - sc_* - System and Communications Protection - si_* - System and Information Integrity - hpc_* - HPC-specific controls

Role Structure

Each role follows a standard pattern:

roles/{role_name}/
├── tasks/
│   ├── main.yml      # Implementation tasks
│   ├── verify.yml    # Compliance verification
│   └── evidence.yml  # Evidence collection
├── defaults/main.yml # Default variables
├── vars/main.yml     # Role variables
├── templates/        # Jinja2 templates
├── handlers/main.yml # Service handlers
└── meta/main.yml     # Role metadata

Key Commands

make env              # Create local Python environment
make ee-build         # Build Ansible Execution Environment
make ee-lint          # Lint roles in execution environment
make ee-syntax-check  # Syntax check playbooks
make test             # Run pytest
make docs             # Generate documentation
make assess           # Run compliance assessment

Code Style

• Ansible: Follow ansible-lint rules, use FQCN for modules
• Python: PEP 8, type hints, docstrings
• YAML: 2-space indentation, explicit string quoting

Testing

• Molecule: Role-level testing with delegated driver
• Pytest: Schema validation and integration tests
• Run make ee-lint before committing changes

Active Technologies

• YAML (GitHub Actions workflows), Bash (scripts), Python 3.9+ (existing tooling) + GitHub Actions, GitHub Pages, shields.io (badges), existing Makefile targets (005-ci-cd-dashboard)
• Git repository, gh-pages branch for published artifacts, JSON files for badge data (005-ci-cd-dashboard)
• Bash (orchestration scripts), Ansible 2.15+ (provisioning), Ruby (Vagrantfile) + Vagrant 2.3+, VirtualBox 7.0+ / libvirt / vagrant-qemu, Ansible (006-vagrant-demo-lab)
• NFS shared storage on mgmt01, local VM disks via Vagran (006-vagrant-demo-lab)
• Bash (wrapper scripts), HCL (Terraform 1.5+), Python 3.9+ (inventory generation) + Terraform (Hetzner provider), Ansible 2.15+, existing demo/playbooks/* (007-cloud-demo-infra)
• Terraform state (local file, optional Terraform Cloud remote) (007-cloud-demo-infra)
• Bash (POSIX-compatible with Bash extensions, matching existing scripts), Ansible 2.16+ (post-restore playbook), Python 3.9+ (date parsing helper, inline) + hcloud CLI 1.42+, Terraform 1.7+ (for cold-build only), Ansible 2.16+, jq (JSON parsing), openssh-clien (008-cloud-snapshot-lifecycle)
• Local JSON manifest file (infra/terraform/snapshot-manifest.json), Hetzner Cloud snapshot storage (remote) (008-cloud-snapshot-lifecycle)
• Bash (POSIX-compatible with Bash extensions, matching existing scripts), Ruby (Vagrantfile) + Vagrant 2.3+, vagrant-libvirt (libvirt provider), vagrant-qemu (QEMU provider), jq (JSON parsing), qemu-img (QEMU disk operations) (009-vagrant-prebaked-boxes)
• Local filesystem (demo/vagrant/boxes/), JSON manifest file (009-vagrant-prebaked-boxes)

Recent Changes

• 005-ci-cd-dashboard: Added YAML (GitHub Actions workflows), Bash (scripts), Python 3.9+ (existing tooling) + GitHub Actions, GitHub Pages, shields.io (badges), existing Makefile targets